Repository navigation
Deprecate a decimal hour in a zone offset - #190
Conversation
jeremyevans
left a comment
There was a problem hiding this comment.
I think it would be better to deprecate fractional hour support in offsets, and only handle full hour or hour:minute. From some brief searching, I couldn't find any popular programming language support for fractional hour offsets, and Ruby's Time does not support it either.
|
That makes sense to me, and your premise checks out —
One adjustment to the scope, and it is the reason I am posting the table rather than just agreeing: "only full hour or hour:minute" would also drop The other thing worth noting is the last row. Happy to redo this PR as the deprecation. Two questions on shape:
One implementation note carried over from #191: |
|
Deprecation similar to #191 is best. In terms of the warning, we should warn any case where a parsing the fractional offset hour affects the resulting return value. If the fractional offset part is already ignored, there is no need to warn, because the behavior will change to ignoring the value. |
|
Understood on the shape — deprecation like #191. Before I write it, one thing your rule decides differently depending on which API is asked, so I would rather show you than guess. Measured on 3.2.11, decimal-fraction offsets only (the
The last two rows are the awkward ones. Three or more fractional digits make So for Two ways to resolve it:
I lean towards (1) — the thing being deprecated is the |
|
It's really bad to emit a deprecation warning when the behavior will not change. You are not limited to adding a deprecation warning in a single place. You can add a warning in |
Date._parse and friends honour a fractional hour, so ignoring it later will change what they return; they warn whenever the fraction is not zero. DateTime.civil goes through offset_to_sec, which already drops a zone whose fraction makes the offset non-integral. It warns only where the offset it returns today differs from the one the whole hour alone would give, so '+00.123' stays quiet while '+01.123' does not. date_zone_to_diff keeps its signature and warns; offset_to_sec uses a new date_zone_to_diff_frac that reports the fraction instead.
d4b23cf to
dc922c2
Compare
|
Reworked to deprecation only; nothing returns a different value than before. Two warnings, gated separately as you described. That second gate is what splits the two cases you asked about. Measured on master, then on this branch:
Writing the test for the quiet rows caught something worth mentioning:
Disclosure: written with the help of Claude (an AI assistant). The tables are from runs on my machine. |
|
|
||
| if (frac) | ||
| rb_warning("fraction of hour in a zone offset is deprecated" | ||
| " and will be ignored"); |
There was a problem hiding this comment.
| " and will be ignored"); | |
| " and will be ignored in a future version"); |
Similar change for the other warning.
| assert_equal(1800, Date._parse('2001-02-03T00:00:00+00.5')[:offset]) | ||
| end | ||
| # A zero fraction changes nothing, so it must stay quiet. | ||
| assert_warning('') do |
There was a problem hiding this comment.
This should warn, because while the :offset entry returned may not change, the :zone entry should change to remove the .0
| end | ||
| end | ||
|
|
||
| def capture_zone_warning |
There was a problem hiding this comment.
Is there a reason for this approach instead of assert_warning?
| VALUE offset = date_zone_to_diff_frac(str, &frac, &whole); | ||
|
|
||
| if (frac) | ||
| rb_warning("fraction of hour in a zone offset is deprecated" |
There was a problem hiding this comment.
Add the following block up to near the top of the file (copied from date_core.c):
#ifndef HAVE_RB_CATEGORY_WARN
#define rb_category_warn(category, fmt) rb_warn(fmt)
#endifthen switch to:
| rb_warning("fraction of hour in a zone offset is deprecated" | |
| rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, "fraction of hour in a zone offset is deprecated" |
Similar change for the other warning, except there you would just move the block up in the same file.
| if (out_of_range(sec, 0, 59)) return Qnil; | ||
| } | ||
| } | ||
| else if (*p == ',' || *p == '.') { |
There was a problem hiding this comment.
Crazy, this supports , in addition to .
We should do a manual check that removing this else if branch only breaks the deprecated behavior tests and no other tests.
|
|
||
| class TestDateParse < Test::Unit::TestCase | ||
|
|
||
| def test__parse_fractional_zone_offset_deprecated |
There was a problem hiding this comment.
There should be tests added for Date._strptime, which should have appropriate warnings
Address review: warn through rb_category_warn(RB_WARN_CATEGORY_DEPRECATED), say the fraction will be ignored in a future version, and warn from the parse methods for a zero fraction too, since :zone will change. Tests use assert_warning, cover Date._strptime, and the existing fractional-offset rows of the parse and strptime tables move into the deprecation tests.
|
Updated in 37182a3:
Manual check on the Tests pass on Ruby 2.6, 2.7, 3.0 and 3.4 (150 tests). |
|
It looks like we will be replacing the C implementation of DateTime with a Ruby implementation before Ruby 4.1 (see #155). Considering that, I would like to delay review of this PR until after the replacement. Then this issue can be fixed in the Ruby implementation (assuming it exists there). |
|
The revised plan now has us merging the Ruby implementation of Date after Ruby 4.1, so I think we should merge this support now, so the deprecation makes it into Ruby 4.1, and that way the Ruby implementation of Date will not need this complexity. |
|
This looks mostly ready. However, I found one issue. This has DateTime.civil(2000, 1, 2, 3, 4, 5, '+01.123')
# warning: fraction of hour in a zone offset is deprecated and will be ignored in a future version
# warning: invalid offset is ignoredIf we are already warning that we are ignoring the offset, I don't think we need to add a deprecation warning for this case. Additionally, the deprecation warning implies that we currently are respecting the fractional hour and will start ignoring it in the future, when we are already ignoring it. |
DateTime.civil with '+01.123' warned both that the fraction is deprecated and that the invalid offset is ignored. Warn about the fraction only when offset_to_sec accepts the offset.
|
Fixed in 43c5f2d. I checked the other methods with |
|
Perhaps "decimal hour" would be a little clearer than "fraction of hour" in the warning. While the code calls it a fractional hour internally, it was non-obvious to me at first glance. I was also wondering if raising |
I agree that "decimal hour" would be clearer.
I think that would be inconsistent unless we start raising for invalid offsets in Regarding #191, it makes sense to raise, because the format is invalid and We should never raise for |
|
Changed the warning to "decimal hour in a zone offset is deprecated and will be ignored in a future version" in 52bdb78, for both the parse methods and the constructors. The suite passes on Ruby 3.4 and 2.6 with this branch merged into master. |
Deprecates a decimal hour in a zone offset (for example
+05.5), as discussed below. No method returns a different value yet.Date._parse,Date._strptimeand the methods built on them) warn when the zone has a fractional hour, including+01.0, since:offsetor:zonewill change once the fraction is ignored.offset_to_sec(DateTime.civil,jd,new_offsetand the other constructors) warns only when it accepts the offset and the fraction changes it. An offset it already ignores as invalid gets only the existing "invalid offset is ignored" warning.Both use
rb_category_warn(RB_WARN_CATEGORY_DEPRECATED, ...), so on Ruby 2.7+ they appear only with deprecation warnings enabled.Tests are in
test_date_new.rb,test_date_parse.rbandtest_date_strptime.rb; the existing fractional rows intest__parseandtest__strptime__3moved into the deprecation tests. The full suite passes on Ruby 3.4 and 2.6 with this branch merged into master.I used an AI assistant to help prepare this change; I reviewed and tested it.